home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 August: Tool Chest / Dev.CD Aug 94.toast / Sample Code / System 7.0 Samples / DTS.Utilities / Utilities.h < prev    next >
Encoding:
C/C++ Source or Header  |  1991-02-13  |  25.1 KB  |  617 lines  |  [TEXT/MPS ]
  1. /*-----------------------------------------------------------------------------------------
  2. #
  3. #    Apple Macintosh Developer Technical Support
  4. #
  5. #    Collection of Utilities for DTS Sample code
  6. #
  7. #    Program:    Utilities.c.o
  8. #    File:        Utilities.h    -    Header for C Source
  9. #
  10. #    Copyright © 1988-1990 Apple Computer, Inc.
  11. #    All rights reserved.
  12. #
  13. -----------------------------------------------------------------------------------------*/
  14.  
  15. #ifndef __UTILITIES__
  16. #define __UTILITIES__
  17.  
  18. #ifdef applec
  19.  
  20. #    ifndef __TYPES__
  21. #        include <Types.h>
  22. #    endif
  23.  
  24. #    ifndef __QUICKDRAW__
  25. #        include <QuickDraw.h>
  26. #    endif
  27.  
  28. #    ifndef __DIALOGS__
  29. #        include <Dialogs.h>
  30. #    endif
  31.  
  32. #    ifndef __FILES__
  33. #        include <Files.h>
  34. #    endif
  35.  
  36. #    ifndef __MEMORY__
  37. #        include <Memory.h>
  38. #    endif
  39.  
  40. #    ifndef __OSUTILS__
  41. #        include <OSUtils.h>
  42. #    endif
  43.  
  44. #    ifndef __WINDOWS__
  45. #        include <Windows.h>
  46. #    endif
  47.  
  48. /* 
  49.  *    If we are using MPW 3.2 or later, GestaltEqu.h is included, otherwise we use
  50.  *    GestaltEqu31.h included in ::SC.025.Utilities:
  51.  */
  52. #    ifndef __GESTALTEQU__
  53. #        ifdef MPW32
  54. #            include <GestaltEqu.h>
  55. #        else
  56. #            include "GestaltEqu31.h"
  57. #        endif
  58. #    endif
  59.  
  60. /* 
  61.  *    If we are using MPW 3.2 or later, Folders.h is included, otherwise we use
  62.  *    definitions included in ::SC.025.Utilities:
  63.  */
  64. #    ifndef __FOLDERS__
  65. #        ifdef MPW32
  66. #            include <Folders.h>
  67. #        else
  68. #            include "Folders31.h"
  69. #        endif
  70. #    endif
  71.  
  72. #endif
  73.  
  74. #include "UtilitiesCommon.h"
  75.  
  76. /*-----------------------------------------------------------------------------------------
  77.     Global constants
  78. -----------------------------------------------------------------------------------------*/
  79. #ifndef applec
  80. #define nil                        0L
  81. #define _WaitNextEvent                    0xA860
  82. #define _InitGraf                        0xA86E
  83. #define _Unimplemented                    0xA89F
  84. /*
  85. #define screenActive            15    
  86. */
  87. #endif
  88.  
  89. #define    kOSEvent                app4Evt        /* event used by MultiFinder */
  90. #define    kSuspendResumeMessage    1            /* high byte of suspend/resume event message */
  91. #define    kResumeMask                1            /* bit of message field for resume vs. suspend */
  92. #define    kMouseMovedMessage        0xFA        /* high byte of mouse-moved event message */
  93. #define    kNoEvents                0            /* no events mask */
  94.  
  95. #define kDelayTime                8            /* For the delay time when flashing the
  96.                                                menubar and highlighting a button.
  97.                                                8/60ths of a second*/
  98.  
  99. #define kStartPtH                2            /* offset from the left of the screen */
  100. #define kStartPtV                2            /* offset from the top of the screen */
  101. #define kStaggerH                12            /* staggering amounts for new windows */
  102. #define kStaggerV                16
  103.  
  104. #define chBackspace                '\b'        /* ASCII code for Backspace character */
  105. #define chClear                    '\033'        /* ASCII code for Clear key (aka ESC) */
  106. #define chDown                    '\037'        /* ASCII code for down arrow */
  107. #define chEnd                    '\004'        /* ASCII code for the End key */
  108. #define chEnter                    '\003'        /* ASCII code for Enter character */
  109. #define chEscape                '\033'        /* ASCII code for Escape (aka Clear) key */
  110. #define chFunction                '\020'        /* ASCII code for any function key */
  111. #define chFwdDelete                '\177'        /* ASCII code for forward delete */
  112. #define chHelp                    '\005'        /* ASCII code for Help key */
  113. #define chHome                    '\001'        /* ASCII code for the Home key */
  114. #define chLeft                    '\034'        /* ASCII code for left arrow */
  115. #define chPageDown                '\f'        /* ASCII code for Page Down key */
  116. #define chPageUp                '\013'        /* ASCII code for Page Up key */
  117. #define chReturn                '\n'        /* ASCII code for Return character */
  118. #define chRight                    '\035'        /* ASCII code for right arrow */
  119. #define chSpace                    ' '            /* ASCII code for Space character */
  120. #define chTab                    '\t'        /* ASCII code for Tab character */
  121. #define chUp                    '\036'        /* ASCII code for up arrow */
  122.  
  123. enum { kQDOriginal = 0, kQD8Bit, kQD32Bit };    /* For use with gQDVersion */
  124.  
  125. /*-----------------------------------------------------------------------------------------
  126.     Types
  127. -----------------------------------------------------------------------------------------*/
  128.  
  129. typedef short *IntegerPtr, **IntegerHandle;
  130.  
  131. typedef long *LongintPtr, **LongintHandle;
  132.  
  133. typedef Boolean *BooleanPtr, **BooleanHandle;
  134.  
  135. typedef Rect *RectPtr, **RectHandle;
  136.  
  137. struct    WindowTemplate    {                    /*template to a WIND resource*/
  138.     Rect    boundsRect;
  139.     short    procID;
  140.     Boolean    visible;
  141.     Boolean    filler1;
  142.     Boolean    goAwayFlag;
  143.     Boolean    filler2;
  144.     long    refCon;
  145.     Str255    title;
  146. };
  147. typedef    struct    WindowTemplate    WindowTemplate;
  148. typedef            WindowTemplate    *WindowTPtr, **WindowTHndl;
  149.  
  150. /* following is here to account for lapses in the THINK C headers */
  151.  
  152. #ifndef applec
  153. /*
  154. typedef unsigned char TrapType;
  155. */
  156. struct NumVersion {
  157.     unsigned char majorRev;         /* 1st part of version number in BCD*/
  158. /*    unsigned short minorRev : 4;        2nd part is 1 nibble in BCD*/
  159. /*    unsigned short bugFixRev : 4;         3rd part is 1 nibble in BCD*/
  160.     unsigned char minorAndBugFixRev;
  161.     unsigned char stage;            /*stage code: dev, alpha, beta, final*/
  162.     unsigned char nonRelRev;        /*revision level of non-released version*/
  163. };
  164.  
  165. typedef struct NumVersion NumVersion;
  166. /* Numeric version part of 'vers' resource */
  167. struct VersRec {
  168.     NumVersion numericVersion;        /*encoded version number*/
  169.     short countryCode;                /*country code from intl utilities*/
  170.     Str255 shortVersion;            /*version number string - worst case*/
  171.     Str255 reserved;                /*longMessage string packed after shortVersion*/
  172. };
  173.  
  174. typedef struct VersRec VersRec;
  175. typedef VersRec *VersRecPtr, **VersRecHndl;
  176.  
  177. /*
  178. typedef WStateData *WStateDataPtr, **WStateDataHandle;
  179. */
  180.  
  181. #define Length(string) (*(unsigned char *)(string))
  182. #ifndef THINK_C
  183. #define Gestalt            GESTALT
  184. #define NewGestalt        NEWGESTALT
  185. #define ReplaceGestalt    REPLACEGESTALT
  186. #endif
  187. #endif
  188.  
  189.  
  190. typedef Rect (*PositionWndProcPtr)(WindowPtr window, WindowPtr relatedWindow);
  191.  
  192.  
  193. /*-----------------------------------------------------------------------------------------
  194.     Handy Macros/inlines
  195. -----------------------------------------------------------------------------------------*/
  196. #ifdef false                                        /* The c++ stuff is turned OFF!!! */
  197.  
  198. inline long abs(val) 
  199. {    return ((val < 0) ? (-val) : (val)); }            /* Absolute value */
  200.  
  201. inline void PStrCopy(dest, src)                        /* Pascal string copy */
  202. {    BlockMove (src, dest, (*(char *)(src))+1); }
  203.  
  204. inline Point* TopLeft(Rect& r)                        /* provide access to rect.topLeft  */
  205. {    return (Point*)(&r.top); }
  206.  
  207. inline Point* BotRight(Rect& r)                        /* provide access to rect.botRight  */
  208. {    return (Point*)(&r.bottom); }
  209.  
  210. inline short HiWrd(long aLong)                        /* return the hi word of a long */
  211. {    return ((aLong >> 16) & 0xFFFF); }
  212.  
  213. inline short LoWrd(long aLong)                        /* return the lo word of a long */
  214. {    return (aLong & 0xFFFF); }
  215.  
  216. inline void SETPT(Point *pt,short h,short v)
  217. {    (*pt).h = h; (*pt).v = v); }
  218.  
  219. inline void SETRECT(Rect *r,short left,short top,short right,short bottom)
  220. {    SETPT(TopLeft(*r), left, top); SETPT(BotRight(*r), right, bottom); }
  221.  
  222. /* 
  223.  *    Useful functions for testing gestalt attribute responses
  224.  *
  225.  *    BTstBool returns a true boolean value (0 or 1), but is slower than:
  226.  *    BTstQ which simply returns a non-zero value if the bit is set which
  227.  *    means the result could get lost if assigned to a short, for example.
  228.  *
  229.  *    arg is any integer value, bitnbr is the number of the bit to be tested.
  230.  *    bitnbr = 0 is the least significant bit.
  231.  */
  232. inline short BTstBool(arg, bitnbr)    
  233. {    return ((arg >> bitnbr) & 1); }
  234.  
  235. inline long BTstQ(arg, bitnbr)
  236. {    return (arg & (1 << bitnbr)); }
  237.  
  238. #else
  239.  
  240.  
  241. #ifndef THINK_C
  242. #define QD(whatever) (qd.##whatever)
  243. #else
  244. #define QD(whatever) (whatever)
  245. #endif
  246.  
  247.  
  248. /* define our own abs() so we don't need StdLib */
  249. #define abs(val) (((val) < 0) ? (-(val)) : (val))
  250. /* Pascal string copy */
  251. #define PStrCopy(dest, src)    (BlockMove (src, dest, (*(char *)(src))+1))
  252. #define TopLeft(r)        (* (Point *) &(r).top)
  253. #define BotRight(r)        (* (Point *) &(r).bottom)
  254. #define HiWrd(aLong)    (((aLong) >> 16) & 0xFFFF)
  255. #define LoWrd(aLong)    ((aLong) & 0xFFFF)
  256. #define MIN(a, b) ((a) < (b) ? (a) : (b) )
  257. #define MAX(a, b) ((a) > (b) ? (a) : (b) )
  258. #define SETPT(pt, x, y)    (*(pt)).h = (x); (*(pt)).v = (y)
  259. #define SETRECT(r, left, top, right, bottom)    \
  260.                         SETPT(&TopLeft(*(r)), (left), (top)); \
  261.                         SETPT(&BotRight(*(r)), (right), (bottom))
  262. /* 
  263.  *    Useful macros for testing gestalt attribute responses
  264.  *
  265.  *    BTstBool returns a true boolean value (0 or 1), but is slower than:
  266.  *    BTstQ which simply returns a non-zero value if the bit is set which
  267.  *    means the result could get lost if assigned to a short, for example.
  268.  *
  269.  *    arg is any integer value, bitnbr is the number of the bit to be tested.
  270.  *    bitnbr = 0 is the least significant bit.
  271.  */
  272. #define BTstBool(arg, bitnbr)    ((arg >> bitnbr) & 1)
  273. #define BTstQ(arg, bitnbr)        (arg & (1 << bitnbr))
  274.  
  275. #endif
  276.  
  277. /*-----------------------------------------------------------------------------------------
  278.     Global variables
  279. -----------------------------------------------------------------------------------------*/
  280. /*    The following global variables are initialized by StardardInitialization to
  281.  *    define the environnment.  This used to be a single SysEnvRec, but now,
  282.  *    all those variables defined in a SysEnvRec can be returned by Gestalt
  283.  *    (except sysVRefNum; see FindSysFolder).  Note that all the variables
  284.  *    below will be correctly initialized whether Gestalt is available or not;
  285.  *    the Gestalt glue handles this.
  286.  */
  287. extern short            gMachineType;            /* which machine this is */
  288. extern short            gSystemVersion;            /* System version number */
  289. extern short            gProcessorType;            /* which CPU this is */
  290. extern Boolean            gHasFPU;                /* true if machine has an FPU */
  291. extern short            gQDVersion;                /* major QD version #; 0 for original, 
  292.                                                     1 for color QD, 2 for 32-bit QD */
  293. extern short            gKeyboardType;            /* which type of keyboard is present */
  294. extern short            gAppleTalkVersion;        /* AppleTalk version number */
  295.         
  296. /*    These are also handled by Gestalt. gHasPMMU has no corresponding SysEnvRec
  297.  *    field, but it is handled by the glue, so we include it here for completeness.
  298.  *    gAUXVersion will be initialized with Gestalt if present, but correctly
  299.  *    set even if Gestalt is not available
  300.  */
  301. extern Boolean            gHasPMMU;                /* true if machine has a PMMU or equivalent */
  302. extern short            gAUXVersion;            /* major A/UX version number (0 if not present) */
  303.  
  304. /*    
  305.  *    gHasWaitNextEvent is set to TRUE if the Macintosh we are running on has
  306.  *    WaitNextEvent implemented. We can use this in our main event loop to
  307.  *    determine whether to call WaitNextEvent or GetNextEvent.
  308.  */
  309. extern Boolean            gHasWaitNextEvent;
  310.  
  311. /*
  312.  *    gAppResRef is the application’s resource file reference. I need to save
  313.  *    this since I can open other resource files. The current resource file is
  314.  *    always gAppResRef unless I momentarily set it to another file to read its
  315.  *    resources, and then immediately restore it back.
  316.  */
  317. extern short            gAppResRef;
  318.  
  319. /*
  320.  *    gInBackground is maintained by our osEvent handling routines. Any part of
  321.  *    the program can check it to find out if it is currently in the background.
  322.  */
  323. extern Boolean            gInBackground;            /* maintained by StandardInitialization
  324.                                                       and DoEvent */
  325.                                                       
  326. /*
  327.  *    gAppName holds the name of the application that's running. You can use if
  328.  *    for any purpose you'd like. It is also used by StandardAbout if it can't
  329.  *    find a string to use for the application name in a resource, so make sure
  330.  *    you call InitForStandardAbout if you are going to call StandardAbout. If you
  331.  *    call StandardInitialization, this is done for you.
  332.  */
  333. extern Str255            gAppName;
  334.  
  335. /*
  336.  *    gSignature holds the creator signature for the running application. It follows the
  337.  *    same rules as those for gAppName.
  338.  */
  339. extern OSType            gSignature;
  340.  
  341. /*
  342.  *    Initial values of these global variables are set to zero or FALSE by MPW's 
  343.  *    runtime initialization routines.  If the Utilities initialization routines
  344.  *    have been properly called, then gUtilitiesInited will be true.  If it is
  345.  *    not true, then the values of the above global variables are invalid.
  346.  */
  347. extern Boolean            gUtilitiesInited;
  348.  
  349. /*-----------------------------------------------------------------------------------------
  350.     Interface to routines
  351. -----------------------------------------------------------------------------------------*/
  352.  
  353. #ifdef __cplusplus
  354. extern "C" {
  355. #endif
  356.  
  357. short        CenteredAlert(short alertID, WindowPtr relWindow);
  358.             /* Given an Alert ID and a related window pointer, this routine will center
  359.                the alert on the same device as the related window.  If the related
  360.                window pointer is nil, then the alert will be centered on the device
  361.                that the alert would normally be placed if Alert was called directly. */
  362.  
  363. void        CenterRectInRect(Rect outerRect, Rect *innerRect);
  364.             /* Given two rectangles, this routine centers the second one within the first. */
  365.  
  366. Rect        CenterWindow(WindowPtr window, WindowPtr relatedWindow);
  367.             /* Given a window pointer and a related window pointer, this routine will
  368.                center the window on the same device as the related window.  If the
  369.                related window pointer is nil, then the window will be centered on the
  370.                device that the window already is.
  371.                WARNING: This routine may move or purge memory. */
  372.  
  373. void        CloseAnyWindow(WindowPtr window);
  374.             /* Closes the indicated window.  Does the right thing, taking into account
  375.                that the window may belong to a DA.
  376.                WARNING: An application window is closed via a CloseWindow call.  Use
  377.                            this call when you want to keep the storage for the window
  378.                         record.  (Compare against DisposeAnyWindow.) */
  379.  
  380. void        DisposeAnyWindow(WindowPtr window);
  381.             /* Disposes of the indicated window.  Does the right thing, taking into account
  382.                that the window may belong to a DA.
  383.                WARNING: An application window is closed via a DisposeWindow call.  Use
  384.                            this call when you want to free up the storage for the window
  385.                         record.  (Compare against CloseAnyWindow.) */
  386.  
  387. void        DeathAlert(short errResID, short errStringIndex);
  388.             /* Display an alert that tells the user an error occurred, then exit the
  389.                program. This routine is used as an ultimate bail-out for serious errors
  390.                that prohibit the continuation of the application. */ 
  391.  
  392. void        DeathAlertMessage(short errResID, short errStringIndex, short message);
  393.  
  394. void        ErrorAlert(short errResID, short errStringIndex);
  395.  
  396. void        ErrorAlertMessage(short errResID, short errStringIndex, short message);
  397.  
  398. OSErr        FindSysFolder(short *foundVRefNum, long *foundDirID);
  399.             /* FindSysFolder returns the (real) vRefNum, and the DirID of the current
  400.                system folder.  It uses the Folder Manager if present, otherwise
  401.                it falls back to SysEnvirons.  It returns zero on success, otherwise
  402.                a standard system error. */
  403.  
  404. Handle        GetAppIndResource(ResType theType, short index, OSErr *err);
  405.             /* GetAppIndResource gets a resource from the application's res file by index */
  406.  
  407. Handle        GetAppNamedResource(ResType theType, Str255 name, OSErr *err);
  408.             /* GetAppNamedResource gets a resource from the application's res file by name */
  409.  
  410. Handle        GetAppResource(ResType theType, short theID, OSErr *err);
  411.             /* GetAppResource gets a resource from the application's res file by resource ID */
  412.  
  413. short        GetAUXVersion( void);
  414.             /* getAUXVersion -- Checks for the presence of A/UX by whatever means is
  415.                appropriate.  Returns the major version number of A/UX (i.e. 0 if A/UX 
  416.                is not present, 1 for any 1.x.x version 2 for any 2.x version, etc.
  417.                This code should work for all past, present and future A/UX systems. */
  418.  
  419. DialogPtr    GetCenteredDialog(short id, DialogPtr storage, WindowPtr relatedWindow, WindowPtr behind);
  420.             /* Given a dialog ID and a related window pointer, this routine will center
  421.                the dialog on the same device as the related window.  If the related
  422.                window pointer is nil, then the dialog will be centered on the device
  423.                that the dialog would normally be placed if GetNewDialog was called. */
  424.  
  425. WindowPtr    GetCenteredWindow(short id, Ptr storage, WindowPtr relWindow, WindowPtr behind, Boolean inColor);
  426.             /* Given a window ID and a related window pointer, this routine will center
  427.                the window on the same device as the related window.  If the related
  428.                window pointer is nil, then the window will be centered on the device
  429.                that the window would normally be placed if GetNewWindow was called. */
  430.  
  431. Boolean     GetCheckOrRadio(DialogPtr dlgPtr, short itemNo);
  432.  
  433. long        GetGestaltResult(OSType gestaltSelector);
  434.             /* GetGestaltResult returns the result value from Gestalt for the specified
  435.                selector.  If Gestalt returned an error GetGestaltResult returns zero.  Use 
  436.                of this function is only cool if we don't care whether Gestalt returned an 
  437.                error.  In many casesyou may need to know the exact Gestalt error code so 
  438.                then this routine would be inappropriate. */
  439.  
  440. Point        GetGlobalMouse(void);
  441.             /* Returns the location of the mouse in local coordinates. It does this by
  442.                calling OSEventAvail(). */ 
  443.  
  444. Point        GetGlobalTopLeft(WindowPtr window);
  445.             /*     Given a window, this will return the top left point of the window’s port in
  446.                   global coordinates. Something this doesn’t include, is the window’s drag
  447.                   region (or title bar). This returns the top left point of the window’s
  448.                   content area only. */
  449.  
  450. long        GetKFreeSpace(short vRefNum);
  451.  
  452. Rect        GetMainScreenRect(void);
  453.  
  454. GDHandle    GetRectDevice(Rect globalRect);
  455.             /* Find the greatest overlap device for the given global rectangle. */
  456.  
  457. Rect        GetRectDeviceRect(Rect globalRect);
  458.             /* Find the rect of the greatest overlap device for the given global rect. */
  459.  
  460. WindowPtr    GetSomeKindOfWindow(PositionWndProcPtr whatKind, short windID, Ptr storage, WindowPtr relWindow, WindowPtr behind, Boolean inColor);
  461.             /* Given a window positioning procedure pointer, a window ID and a window
  462.                pointer the window relates to, this function open a new window by either
  463.                a NewCWindow or a NewWindow call, depending on the value of inColor.  The
  464.                window will be opened invisible, independent of what the resource says.
  465.                Once the window is opened successfully, the positioning procedure is
  466.                called.  The positioning procedure is passed a pointer to the just-opened
  467.                invisible window and a pointer to the related window.  It is up to the
  468.                positioning procedure to move the invisible window to the correct location
  469.                on the correct device.  Once the positioning procedure returns, the window
  470.                will be made visible if so indicated by the resource. */
  471.  
  472. WindowPtr    GetStaggeredWindow(short id, Ptr storage, WindowPtr relWindow, WindowPtr behind, Boolean inColor);
  473.             /* Given a window ID and a window pointer the window relates to, this function
  474.                will stagger the window’s rectangle before showing it on the proper screen.
  475.                This follows the Apple Human Interface Guidelines for where to place a
  476.                staggered window on the screen.  If the window is not closely associated
  477.                with another window, pass a nil for the window pointer of the related
  478.                window.  If you pass a nil, the window is simply displayed where the
  479.                resource would indicate. */
  480.  
  481. TrapType    GetTrapType(short theTrap);
  482.             /* Returns the type (OSType or ToolType) of the trap. It does this by checking
  483.                the bits of the trap word. */ 
  484.  
  485. Rect        GetWindowContentRect(WindowPtr window);
  486.             /* Given a window pointer, return the global rectangle that encloses the
  487.                content area of the window. */
  488.  
  489. short        GetWindowCount(Boolean includeDAs, Boolean includeInvisibles);
  490.             /* This procedure counts the number of windows in the application plane.  You have the
  491.                choices of also including DAs and invisible windows in this count. */
  492.  
  493. GDHandle    GetWindowDevice(WindowPtr window);
  494.             /* Find the greatest overlap device for the given window. */
  495.  
  496. Rect        GetWindowDeviceRect(WindowPtr window);
  497.             /* Given a window pointer, find the device that contains most of the window
  498.                and return the device's bounding rectangle. */
  499.  
  500. Rect        GetWindowDeviceRectNMB(WindowPtr window);
  501.             /* Given a window pointer, find the device that contains most of the window
  502.                and return the device's bounding rectangle.  If this device is the main
  503.                device, then remove the menubar area from the rectangle. */
  504.  
  505. Rect        GetWindowStructureRect(WindowPtr window);
  506.             /* This procedure is used to get the rectangle that surrounds the entire
  507.                structure of a window.  This is true whether or not the window is visible.
  508.                If the window is visible, then it is a simple matter of using the bounding
  509.                rectangle of the structure region.  If the window is invisible, then the
  510.                strucRgn is not correct.  To make it correct, then window has to be moved
  511.                way off the screen and then made visible.  This generates a valid strucRgn,
  512.                although it is valid for the position that is way off the screen.  It still
  513.                needs to be offset back into the original position.  Once the bounding
  514.                rectangle for the strucRgn is obtained, the window can then be hidden again
  515.                and moved back to its correct location.  Note that ShowHide is used,
  516.                instead of ShowWindow and HideWindow.  HideWindow can change the plane of
  517.                the window.  Also, ShowHide does not affect the hiliting of windows. */
  518.   
  519. void        GlobalToLocalRect(Rect *aRect);
  520.  
  521. void        InitToolBox(void);
  522.  
  523. void        InitUtilities(void);
  524.             /* This sets up some global variables for use by the utilities package.  If you call
  525.                StandardInitialization, you don't need to call this, as it will do it for you. */ 
  526.  
  527. Boolean        IsAppWindow(WindowPtr window);
  528.             /* Returns TRUE if the windowKind of the window is greater than or equal to
  529.                userKind. If it is less, or the window is NIL, then return FALSE. */ 
  530.  
  531. Boolean        IsDAWindow(WindowPtr window);
  532.             /* Returns TRUE if the windowKind of the window is less than zero. If not, or
  533.                the window is NIL, then return FALSE. */ 
  534.  
  535. void        LocalToGlobalRect(Rect *aRect);
  536.  
  537. char        LockHandleHigh(Handle theHandle);
  538.             /* Does a MoveHHi on the handle and then locks it.  Also, the original state
  539.                of the handle is returned, so you can keep it and set the handle back to it's
  540.                original state with a HSetState call. */
  541.  
  542. short        NumToolboxTraps(void);
  543.             /* Determines the size of the Tool trap table. It does this by sampling a
  544.                couple of trap locations and seeing which, if any are Unimplemented. */ 
  545.  
  546. void        OutlineControl(ControlHandle button);
  547.  
  548. void         OutlineDialogItem(DialogPtr dlgPtr, short item);
  549.  
  550. void        PositionRectInRect(Rect outerRect, Rect *innerRect, Fixed horzRatio, Fixed vertRatio);
  551.             /* Given two rectangles, this routine positions the second within the first one
  552.                so that the it maintains the spacing specified the the horzRatio and vertRatio
  553.                parameters. In other words, to center an inner rectangle hoizontally, but
  554.                have its center be 1/3 from the top of the outer rectangle, call this
  555.                routine with horzRatio = FixRatio(1, 2), vertRatio = FixRatio(1, 3). */
  556.  
  557. void        PullApplicationToFront(void);
  558.             
  559. void        PStrConcat(Str255 targetStr, Str255 appendStr);
  560.             /* Concatenate a Pascal string onto another. */
  561.  
  562. void        SelectButton(ControlHandle button);
  563.             /* Given the button control handle, this will cause the button to look as if it
  564.                has been clicked in. This is nice to do for the user if they type return or
  565.                enter to select the default item. */
  566.  
  567. void        SetCheckOrRadioButton(DialogPtr dlgPtr, short itemNo, short state);
  568.  
  569. Rect        StaggerWindow(WindowPtr window, WindowPtr relatedWindow);
  570.             /* This algorithm for staggering windows does quite a good job.  It also is
  571.                quite gnarly.  Here's the deal:
  572.                There are pre-designated positions that we will try when positioning a
  573.                window.  These slots will be tried from the upper-left corner towards the
  574.                lower-right corner.  If there are other windows in that slot, then we will
  575.                consider that slot taken, and proceed to the next slot.  A slot is
  576.                determined to be taken by checking a point with a slop area.  This slop
  577.                area is diamond-shaped, not simply rectangular.  If there is no other
  578.                visible window with an upper-left corner within the slopt diamond, then
  579.                we are allowed to position our window there.
  580.                The above rule holds true unless this forces the window to be partly
  581.                off the screen.  If the window ends up partly off the screen, then we give
  582.                up and just put it in the first slot. */
  583.  
  584. void        StandardAbout(short appNameStringID);
  585.             /* Shows a standard about box with the name of the application, its version
  586.                number, a copyright notice, and DTS credits. Most of this information is
  587.                taking from a standard DITL and the application’s 'vers' resource. The name
  588.                of the application is taken either from the 'STR ' resource passed in to
  589.                this routine, or from GetAppParms() if that resource doesn’t exist, or you
  590.                pass in -1. */ 
  591.  
  592. void        StandardInitialization(short callsToMoreMasters);
  593.             /* Initializes “gInBackGround” to FALSE. Makes the following InitXXX calls:
  594.                InitGraf(), InitFonts(), InitWindows(), InitMenus(), TEInit(),
  595.                InitDialogs(), InitCursor(). Brings application to front with 3 EventAvail
  596.                calls. Calls SysEnvirons to initialize “gMac”. Calls TrapExists() to
  597.                initialize “gHasWaitNextEvent”. */ 
  598.    
  599. void        StandardMenuSetup(short MBARID, short AppleMenuID);
  600.             /* Installs and draws the menus indicated by 'MBAR'(MBARID). Adds DA’s to the
  601.                menu indicated by AppleMenuID by calling AddResMenu. If the menuBar cannot
  602.                be created, the alert specified by rDeathAlert is displayed. */   
  603.  
  604. void         ToggleCheck(DialogPtr dlgPtr, short cChkItem);
  605.  
  606. Boolean        TrapExists(short theTrap);
  607.             /* Returns TRUE if the trap exists (i.e., it’s callable without getting DS
  608.                error 12) */ 
  609.  
  610. void        ZoomToWindowDevice(WindowPtr window, short maxWidth, short maxHeight,
  611.                                short zoomDir, Boolean front);
  612.  
  613. #ifdef __cplusplus
  614. }
  615. #endif
  616.  
  617. #endif